Audit Policy

The audit policy feature provides you with a way to prompt a user to provide a reason why they are performing a specific action (e.g. modifying a job, or manually triggering a job that typically only runs on a schedule, etc.). The reason entered by the user (which can be optional or required) is saved in the audit history of the object or instance (both object and instance audit policies are supported).

 

Audit policies can be set (created) at the root of the Job Scheduler and on any folder or plan object (the three ActiveBatch containers). The audit policies are applied to objects that have the container within their full path. Since audit policies are created on the container-level, you can configure different policies for different containers. For example, assume an audit policy is added to FolderA. The audit policy operation configured is "Update" (there are several to choose from, described below). Update means an object has been modified (i.e. one or more object properties have been changed). When a user changes an object in FolderA, they will be prompted to enter a reason why they are modifying the object. This reason is added to the object's audit trail, accessible via the object's Analytics tab.

 

Prompting users to add additional audit information using audit policies is purely optional. This feature is often used in a production scheduler environment requiring users explain actions that might not normally occur (or be allowed) in this environment.  For example, your organization may not typically allow a user to change object properties in a production environment. That is, rules may be established where object changes must be made in a test scheduler environment first, then promoted to QA, then promoted to production. That is the standard procedure. However, in a situation where time does not allow for this (it's an urgent fix), and a change is made in the production environment, the reason for bypassing set procedures can be required when an audit policy is configured.

 

How to create an audit policy

 

Using the Navigation pane, right click on the desired container (Scheduler root, folder or plan) that you wish to create an audit policy for. Select Policy > Auditing.

 

An Auditing Policies window will pop up, as depicted in the image below. If there are any policy(s) already created for the Add operation (the default operation), you would see them listed in the grid beneath the Add field. In this example, there are no audit policies set for the Add operation, hence the grid is empty.

 

 

When clicking on the dropdown arrow to the right of the Add operation, you will see a list of operations that an audit policy can be created for. Add is one of 7 options.

 

In the example below, the Trigger operation (outlined in red in the list) is a different color when compared to the rest of the operations. This means that the Trigger operation has an audit policy configured.

 

 

If Trigger is selected from the above list, you will see details about the Trigger audit policy in the Auditing Policies dialog, depicted in the image below.

 

 

If you double-click on the row in the above grid, you will be able to edit the audit policy, as depicted in the image below.

 

 

Below is a description of the audit policy fields. These are the same fields you will see for all 7 audit operations supported.

 

Name/Label: This field identifies the audit field. The audit must be unique within the audits established for the operation. The name must also adhere to the general character set requirements established for naming an object.

 

Description: This field describes the audit. As you will be asking your user/operator to enter information for the audit, the description should be able to indicate what information you require.

 

Optional/Required: This field determines whether information must be entered by the user for the operation to be attempted. For a required field, if the information is not specified, the user will receive an error.

 

The following operations support audit policies.

 

Operation	Description
Add	When new objects are created.
Update	When an object is updated.
Move	When an object is moved to a container where a move audit policy is configured.
Trigger	When a Plan or Job is triggered (specifically using the Trigger operation).
Delete	When an object definition is deleted (the audit is added to the deleted object's parent container).
Template Operations	Any operation that is specific to a definition. Depending on the object type, template operations include: Enable, Disable, Soft Disable and Hold. For queues, template operations include: Stop, Start, Open, and Close.
Instance Operations	Any operation that is specific to an instance (for example, Abort, Pause/Resume, Restart, etc.). If you delete an instance, the audit is recorded in the object definition that was used to create the instance.

 

Next, to add a new audit policy, select the operation from the dropdown list at the top of the page, then click Add. In the example below, the Update operation was selected, then the Add button was clicked. From there, populate the audit fields (which was done in this example), then click OK to save.

 

 

Next, sometimes it is useful to restrict an audit response to preset values. This means the user selects a response and does not type in their own response. This is accomplished using the $Options feature in the Audit dialog's Description property. This is special syntax used when creating preset values for the user to select from when the audit pop-up window appears. Observe the use of this feature in the image below.

 

The syntax is: $Options=<comma-separated list>. For example:

 

$Options=Management request, Business owner request, IT request

 

 

In the above example, you are specifying that the user may select VAL1 or VAL2 (and only one of those choices). When the audit policy is applied, the the user can only select VAL1 or VAL2.  They cannot manually enter a different value.

 

How the audit policy is applied

 

Assume a job is manually triggered using the right-click Trigger menu option in Web Console. The system will check to see if an audit policy for the trigger operation exists. It checks on the triggered job's parent container first. If it doesn't find an audit policy for the trigger operation there, it looks to the job's next closest container, looking for a trigger operation audit policy. If it doesn't find one there, it keeps looking through all the containers that are part of the job's full path, going all the way to the Job Scheduler root, looking for a trigger audit policy.  If one is not found, nothing happens (the user is not prompted to enter additional audit information). The first audit policy that is found that matches the configured operation (e.g. on the parent container, or on the next level container, etc.) the search for the audit policy is complete (no more searching takes place) and the audit policy is applied. 

 

When the Trigger operation from the example above occurs, the following pop-up window appears, prompting the user to enter the reason for the manual trigger (which was entered in this example). Observe the Name and Description properties of the audit are displayed at the bottom of the image.

 

 

When the Required radio button is configured for the audit, the user must enter information. No specific check regarding what the user enters is performed.

 

The user's response is added to the audit trail of the object that was triggered. This information is located on the Analytics property sheet of the triggerable object, in the Audits section.

 

See additional notes below

 

Audit policies are supported when:

• Using ActiveBatch interfaces (e.g. AbatConsole and WebConsole)

• Using the ActiveBatch COM API, but you must account for the audit policy in your code.  For example:

  call oObject.Auditing.SetField("Why the manual trigger?", "ReasonForTrigger")

 

Audit policies are not supported when:

• Using the ActiveBatch command line interface

• Using the Jobs Library TriggerJob step